<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <title>NAnt - Loggers &amp; Listeners</title>
        <meta http-equiv="Content-Language" content="en-ca" />
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <meta name="description" content="Loggers &amp; Listeners" />
        <link rel="stylesheet" type="text/css" href="../style.css" />
        <style type="text/css">
            .xmlelement {
                color: #660000;
            }
            
            .xmlattribute {
                color: red;
            }

            .xmltext {
                color: blue;
            }

            .xmlcomment {
                color: green;
            }
            
            .xmlcdata {
                color: #FF00CC;
            }
        </style>
    </head>
    <body>
        <table width="100%" border="0" cellspacing="0" cellpadding="2" class="NavBar">
            <tr>
                <td class="NavBar-Cell">
                    <a title="NAnt home page" href="http://nant.sourceforge.net"><b>NAnt</b></a> <img src="../images/arrow.gif" alt="->" width="13" height="9" />
                    <a href="../index.html">Help</a> <img alt="->" src="../images/arrow.gif"/> <a href="index.html">
                        Fundamentals</a> <img height="9" alt="->" src="../images/arrow.gif" width="13" />
                    Loggers &amp; Listeners
                </td>
                <td class="NavBar-Cell" align="right">
                    v0.91-alpha2
                </td>
            </tr>
        </table>
        <h1>Loggers &amp; Listeners</h1>
        <p class="topicstatus">[This is preliminary documentation and subject to change.]</p>
        <h2>Overview</h2>
        <p>
            NAnt has two related features to allow the build process to be monitored: 
            listeners and loggers.
        </p>
        <h3>Listeners</h3>
        <p>
            A listener is alerted of the following events:
        </p>
        <ul>
            <li>
            build started
            </li>
            <li>
            build finished
            </li>
            <li>
            target started
            </li>
            <li>
            target finished
            </li>
            <li>
            task started
            </li>
            <li>
            task finished
            </li>
            <li>
                message logged</li>
        </ul>
        <h3>Loggers</h3>
        <p>
            Loggers extend the capabilities of listeners and add the following features:
        </p>
        <ul>
            <li>
                Receives a handle to the standard output and error print streams and therefore 
                can log information to the console or the <code>-logfile</code>
            specified file.
            </li>
            <li>
                Logging level (<code>-quiet</code>, <code>-verbose</code>, <code>-debug</code>) 
            aware.
            </li>
            <li>
                Emacs-mode aware. This still needs to be implemented.
            </li>
        </ul>
        <h2>Built-in Listeners/Loggers</h2>
        <div class="table">
            <table>
                <colgroup>
                    <col />
                        <col />
                            <col style="TEXT-ALIGN: center" />
                </colgroup>
                <tbody>
                    <tr>
                        <th>
                            Class</th>
                        <th>
                            Description</th>
                        <th>
                            Type</th>
                    </tr>
                    <tr>
                        <td><a href="#DefaultLogger">NAnt.Core.DefaultLogger</a></td>
                        <td>
                            The logger used implicitly unless overridden with the <code>-logger</code> command-line 
                            switch.
                        </td>
                        <td>IBuildLogger</td>
                    </tr>
                    <tr>
                        <td><a href="#MailLogger">NAnt.Core.MailLogger</a></td>
                        <td>
                            Extends <a href="#DefaultLogger">DefaultLogger</a> such that output is still 
                            generated the same, and when the build is finished an e-mail can be sent.
                        </td>
                        <td>IBuildLogger</td>
                    </tr>
                    <tr>
                        <td><a href="#XmlLogger">NAnt.Core.XmlLogger</a></td>
                        <td>
                            Generates output in XML format.
                        </td>
                        <td>IBuildLogger</td>
                    </tr>
                </tbody>
            </table>
        </div>
        <h3><a id="DefaultLogger" />DefaultLogger</h3>
        <p>Simply run NAnt normally, or:</p>
        <blockquote>
            <p><code>NAnt.exe -logger:NAnt.Core.DefaultLogger</code></p>
        </blockquote>
        <h3><a id="MailLogger" />MailLogger</h3>
        <p>
            The MailLogger captures all output logged through DefaultLogger (standard NAnt 
            output) and will send success and failure messages to unique e-mail lists, with 
            control for turning off success or failure messages individually.
        </p>
        <p>Properties controlling the operation of MailLogger are:</p>
        <div class="table">
            <table>
                <colgroup>
                    <col />
                    <col />
                    <col />
                </colgroup>
                <tbody>
                    <tr>
                        <th>
                            Property</th>
                        <th>
                            Description</th>
                        <th>
                            Required</th>
                    </tr>
                    <tr>
                        <td>MailLogger.mailhost</td>
                        <td>The SMTP server to use.</td>
                        <td>No, default is "localhost"</td>
                    </tr>
                    <tr>
                        <td>MailLogger.from</td>
                        <td>The address of the e-mail sender.</td>
                        <td>Yes, if mail needs to be sent.</td>
                    </tr>
                    <tr>
                        <td>MailLogger.failure.notify</td>
                        <td>Send build failure e-mails ?</td>
                        <td>No, default is "true".</td>
                    </tr>
                    <tr>
                        <td>MailLogger.success.notify</td>
                        <td>Send build success e-mails ?</td>
                        <td>No, default is "true".</td>
                    </tr>
                    <tr>
                        <td>MailLogger.failure.to</td>
                        <td>The address to send build failure messages to.</td>
                        <td>Yes, if failure mail is to be sent.</td>
                    </tr>
                    <tr>
                        <td>MailLogger.success.to</td>
                        <td>The address to send build success messages to.</td>
                        <td>Yes, if success mail is to be sent.</td>
                    </tr>
                    <tr>
                        <td>MailLogger.failure.subject</td>
                        <td>The subject of build failure messages.</td>
                        <td>No, default is "Build Failure".</td>
                    </tr>
                    <tr>
                        <td>MailLogger.success.subject</td>
                        <td>The subject of build success messages.</td>
                        <td>No, default is "Build Success".</td>
                    </tr>
                    <tr>
                        <td>MailLogger.failure.attachments</td>
                        <td>The ID of a fileset representing a set of files to attach when the build fails.</td>
                        <td>No.</td>
                    </tr>
                    <tr>
                        <td>MailLogger.success.attachments</td>
                        <td>The ID of a fileset representing a set of files to attach when the build is successful.</td>
                        <td>No.</td>
                    </tr>
                    <tr>
                        <td>MailLogger.body.encoding</td>
                        <td>The encoding type of the body of the e-mail message.</td>
                        <td>No, default is system's ANSI code page.</td>
                    </tr>
                    <tr>
                        <td>MailLogger.smtp.username<sup>1</sup></td>
                        <td>The name of the user to login to the SMTP server.</td>
                        <td>No.</td>
                    </tr>
                    <tr>
                        <td>MailLogger.smtp.password<sup>1</sup></td>
                        <td>The password of the specified user.</td>
                        <td>No.</td>
                    </tr>
                    <tr>
                        <td>MailLogger.smtp.enablessl<sup>1</sup></td>
                        <td>Specifies whether to use SSL to encrypt the connection.</td>
                        <td>No, default is "false".</td>
                    </tr>
                    <tr>
                        <td>MailLogger.smtp.port<sup>1</sup></td>
                        <td>The SMTP server port to connect to.</td>
                        <td>No, default is "25".</td>
                    </tr>
                </tbody>
            </table>
            <p><sup>1</sup> Only available when NAnt is built targeting .NET Framework 1.1 (or equivalent) or higher.</p>            
        </div>
        <p>Usage:</p>
        <blockquote>
            <p><code>NAnt.exe -logger:NAnt.Core.MailLogger</code></p>
        </blockquote>
        <p>Example:</p>
        <pre class="code">
    <span class="xmltext">&lt;</span><span class="xmlelement">project</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger Test"</span> <span class="xmlattribute">default</span><span class="xmltext">="build"&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.mailhost"</span> <span class="xmlattribute">value</span><span class="xmltext">="smtp.wherever.be" /&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.from"</span> <span class="xmlattribute">value</span><span class="xmltext">="me@telenet.be" /&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.failure.notify"</span> <span class="xmlattribute">value</span><span class="xmltext">="true" /&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.success.notify"</span> <span class="xmlattribute">value</span><span class="xmltext">="true" /&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.failure.to"</span> <span class="xmlattribute">value</span><span class="xmltext">="support@home.be" /&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.success.to"</span> <span class="xmlattribute">value</span><span class="xmltext">="support@home.be" /&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.failure.subject"</span> <span class="xmlattribute">value</span><span class="xmltext">="Nightly build failure !" /&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.success.subject"</span> <span class="xmlattribute">value</span><span class="xmltext">="Nightly build successful" /&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.failure.attachments"</span> <span class="xmlattribute">value</span><span class="xmltext">="MailLogger.failure.files" /&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.success.attachments"</span> <span class="xmlattribute">value</span><span class="xmltext">="MailLogger.success.files" /&gt;</span>

        <span class="xmlcomment">&lt;!-- set of files to attach when build fails --&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">fileset</span> <span class="xmlattribute">id</span><span class="xmltext">="MailLogger.failure.files"&gt;</span>
            <span class="xmltext">&lt;</span><span class="xmlelement">include</span> <span class="xmlattribute">name</span><span class="xmltext">="dump.log" /&gt;</span>
            <span class="xmltext">&lt;</span><span class="xmlelement">include</span> <span class="xmlattribute">name</span><span class="xmltext">="trace.txt" /&gt;</span>
        <span class="xmltext">&lt;/</span><span class="xmlelement">fileset</span><span class="xmltext">&gt;</span>

        <span class="xmlcomment">&lt;!-- set of files to attach when build is successful --&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">fileset</span> <span class="xmlattribute">id</span><span class="xmltext">="MailLogger.success.files"&gt;</span>
            <span class="xmltext">&lt;</span><span class="xmlelement">include</span> <span class="xmlattribute">name</span><span class="xmltext">="trace.txt" /&gt;</span>
        <span class="xmltext">&lt;/</span><span class="xmlelement">fileset</span><span class="xmltext">&gt;</span>
    
        <span class="xmltext">&lt;</span><span class="xmlelement">target</span> <span class="xmlattribute">name</span><span class="xmltext">="build"&gt;</span>
            <span class="xmltext">&lt;</span><span class="xmlelement">echo</span> <span class="xmlattribute">message</span><span class="xmltext">=&quot;Starting build&quot; /&gt;</span>
            ....
            <span class="xmltext">&lt;</span><span class="xmlelement">echo</span> <span class="xmlattribute">message</span><span class="xmltext">=&quot;Finished build&quot; /&gt;</span>
        <span class="xmltext">&lt;/</span><span class="xmlelement">target</span><span class="xmltext">&gt;</span>
    <span class="xmltext">&lt;/</span><span class="xmlelement">project</span><span class="xmltext">&gt;</span>
        </pre>
        <h3><a id="XmlLogger" />XmlLogger</h3>
        <p>
            Writes all build information out to an XML file named <code>log.xml</code>, or 
            the value of the <code>XmlLogger.file</code> property if present, when used as 
            a listener. When used as a logger, it writes all output to either the console 
            or to the value of <code>-logfile</code>.
        </p>
        <p>
            Whether used as a listener or logger, the output is not generated until the 
            build is complete.
        </p>
        <p>Usage:</p>
        <blockquote>
            <p>
                <code>NAnt.exe -listener:NAnt.Core.XmlLogger</code><br />
                <code>NAnt.exe -logger:NAnt.Core.XmlLogger -logfile:buildlog.xml</code>
            </p>
        </blockquote>
        <p>Example:</p>
        <pre class="code">
    <span class="xmltext">&lt;</span><span class="xmlelement">buildresults</span> <span class="xmlattribute">project</span><span class="xmltext">="test"&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"&gt;&lt;![</span><span class="xmlcdata">CDATA[Buildfile: file:///D:/nant-test/xmlpeek/default.build]]</span><span class="xmltext">&gt;&lt;/</span><span class="xmlelement">message</span><span class="xmltext">&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"&gt;&lt;![</span><span class="xmlcdata">CDATA[Target framework: Microsoft .NET Framework 1.1]]</span><span class="xmltext">&gt;&lt;/</span><span class="xmlelement">message</span><span class="xmltext">&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"&gt;&lt;![</span><span class="xmlcdata">CDATA[Target<span class="xmltext">(</span>s<span class="xmltext">)</span> specified: build]]</span><span class="xmltext">&gt;&lt;/</span><span class="xmlelement">message</span><span class="xmltext">&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">target</span> <span class="xmlattribute">name</span><span class="xmltext">="build"&gt;</span>
            <span class="xmltext">&lt;</span><span class="xmlelement">task</span> <span class="xmlattribute">name</span><span class="xmltext">="xmlpeek"&gt;</span>
                <span class="xmltext">&lt;</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"&gt;&lt;![</span><span class="xmlcdata">CDATA[Peeking at <span class="xmltext">'D:\nant-test\xmlpeek\input.xml'</span> with XPath expression <span class="xmltext">'x:parameters/x:param'</span>.]]</span><span class="xmltext">&gt;&lt;/</span><span class="xmlelement">message</span><span class="xmltext">&gt;</span>
                <span class="xmltext">&lt;</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"&gt;&lt;![</span><span class="xmlcdata">CDATA[Found <span class="xmltext">'1'</span> nodes with the XPath expression <span class="xmltext">'x:parameters/x:param'</span>.]]</span><span class="xmltext">&gt;&lt;/</span><span class="xmlelement">message</span><span class="xmltext">&gt;</span>
                <span class="xmltext">&lt;</span><span class="xmlelement">duration</span><span class="xmltext">&gt;</span><span style="color: black;">15.625</span><span class="xmltext">&lt;/</span><span class="xmlelement">duration</span><span class="xmltext">&gt;</span>
            <span class="xmltext">&lt;/</span><span class="xmlelement">task</span><span class="xmltext">&gt;</span>
            <span class="xmltext">&lt;</span><span class="xmlelement">duration</span><span class="xmltext">&gt;</span><span style="color: black;">15.625</span><span class="xmltext">&lt;/</span><span class="xmlelement">duration</span><span class="xmltext">&gt;</span>
        <span class="xmltext">&lt;/</span><span class="xmlelement">target</span><span class="xmltext">&gt;</span>
        <span class="xmltext">&lt;</span><span class="xmlelement">duration</span><span class="xmltext">&gt;</span><span style="color: black;">31.25</span><span class="xmltext">&lt;/</span><span class="xmlelement">duration</span><span class="xmltext">&gt;</span>
    <span class="xmltext">&lt;/</span><span class="xmlelement">buildresults</span><span class="xmltext">&gt;</span>
        </pre>
    </body>
</html>
